/**
 * ESLint 配置文件 - 使用新的 Flat Config 格式
 * 这个文件用于配置代码质量检查和规范
 */

// 导入 ESLint 官方推荐规则集
// 提供 JavaScript 代码的基本质量和潜在问题检查
import js from '@eslint/js'

// 导入 Vue.js 的 Prettier 配置，跳过格式化相关规则
// 避免 ESLint 的格式化规则与 Prettier 冲突
import skipFormatting from '@vue/eslint-config-prettier/skip-formatting'

// 导入 Vue.js 的 ESLint 插件
// 提供 Vue 模板和脚本的特定规则检查
import pluginVue from 'eslint-plugin-vue'

// 从 ESLint 配置包导入必要的工具函数
// defineConfig: 提供配置的类型提示和验证
// globalIgnores: 用于配置全局忽略的文件模式
import { defineConfig, globalIgnores } from 'eslint/config'

// 导入全局变量定义
// 提供不同环境（浏览器、Node.js等）的全局变量定义
import globals from 'globals'

// 导入由 unplugin-auto-import 插件自动生成的全局变量配置
// 这个文件包含了所有通过自动导入功能识别的全局变量
// 例如：ref, computed, onMounted, useRoute, defineStore 等
import autoImportConfig from './.eslintrc-auto-import.json'

/**
 * 导出 ESLint 配置数组
 * Flat Config 格式支持多个配置对象，ESLint 会合并它们
 */
export default defineConfig([
  /**
   * 配置1: 指定需要检查的文件范围
   * 定义 ESLint 应该对哪些文件进行检查
   */
  {
    // 配置名称，用于调试和识别
    name: 'app/files-to-lint',

    // 文件匹配模式，使用 glob 语法
    // 匹配所有 .js, .mjs, .jsx, .vue 文件
    files: ['**/*.{js,mjs,jsx,vue}'],
  },

  /**
   * 配置2: 全局忽略的文件和目录
   * 这些文件将完全跳过 ESLint 检查
   */
  globalIgnores([
    // 忽略构建输出目录
    '**/dist/**',
    // 忽略 SSR 构建目录
    '**/dist-ssr/**',
    // 忽略测试覆盖率报告目录
    '**/coverage/**'
  ]),

  /**
   * 配置3: 全局变量配置
   * 定义在代码中可用的全局变量，避免 "未定义变量" 错误
   */
  {
    languageOptions: {
      globals: {
        // 展开浏览器环境的全局变量（window, document, console, setTimeout 等）
        ...globals.browser,

        // 展开自动导入插件生成的全局变量
        // 包括 Vue 组合式 API、Vue Router、Pinia 等自动导入的变量
        ...autoImportConfig.globals,
      },
    },
  },

  /**
   * 配置4: 应用 ESLint 推荐规则
   * 使用 ESLint 官方推荐的基本规则集
   * 检查常见错误、最佳实践和代码质量问题
   */
  js.configs.recommended,

  /**
   * 配置5: 应用 Vue.js 必要规则
   * 使用 vue-eslint-plugin 提供的 Vue 特定规则
   * 检查 Vue 模板和脚本的语法正确性
   */
  ...pluginVue.configs['flat/essential'],

  /**
   * 配置6: 跳过 Prettier 格式化规则
   * 避免 ESLint 的格式化规则与 Prettier 冲突
   * 让 Prettier 专门处理代码格式化，ESLint 专注于代码质量
   */
  skipFormatting,

  /**
   * 配置7: Vue 文件特定规则
   * 只对 .vue 文件应用的特定规则
   */
  {
    // 仅对 Vue 单文件组件生效
    files: ['**/*.vue'],

    // Vue 文件特定的规则配置
    rules: {
      /**
       * Vue 组件命名规则配置
       * 要求组件使用多单词名称（避免与 HTML 原生标签冲突）
       */
      'vue/multi-word-component-names': ['error', {
        // 例外情况：允许以下单单词组件名
        ignores: [
          'index',    // 允许 index.vue（通常是目录的入口文件）
          'default'   // 允许 default.vue（默认导出组件）
        ]
      }]
    }
  }
])
